Fixes #69
Supersedes #70

Reviewer's Guide — PR #79

The Big Idea

This PR introduces a TypeScript-based code generator (scripts/codegen/java.ts) that reads the Copilot CLI's JSON schema files (api.schema.json, session-events.schema.json) and produces strongly-typed Java source files under src/generated/java/. The generated code replaces two categories of hand-written code:

1. Session event classes — A sealed SessionEvent hierarchy (~70 event types) with Jackson @JsonSubTypes polymorphic deserialization, replacing the hand-written com.github.copilot.sdk.events package that is deleted in this PR.

2. Typed RPC wrapper classes — ServerRpc and SessionRpc with namespace sub-APIs (e.g., session.tools, session.ui, session.model), plus ~130 param/result record DTOs. These replace raw rpc.invoke("method.name", Map.of(...), ...) calls throughout CopilotClient and CopilotSession.

After this PR, internal RPC call sites in CopilotSession (tool results, permission handling, command handling, elicitation, model switching, logging) use typed wrappers like:

getRpc().tools.handlePendingToolCall(new SessionToolsHandlePendingToolCallParams(...))
getRpc().permissions.handlePendingPermissionRequest(...)
getRpc().ui.elicitation(new SessionUiElicitationParams(...))
getRpc().model.switchTo(new SessionModelSwitchToParams(...))

Both CopilotClient.getRpc() and CopilotSession.getRpc() are public API, so SDK consumers can call any RPC method the CLI exposes — not just those the SDK wraps with convenience methods.

Supporting infrastructure

• CI workflow codegen-check.yml — Runs the generator and fails if the committed files diverge from what the generator produces.
• Dependency update workflow update-copilot-dependency.yml — Manual workflow_dispatch that bumps @github/copilot in scripts/codegen/package.json, regenerates all files, and opens a PR.
• Prohibition guard — The agentic merge workflow (agentic-merge-reference-impl.prompt.md) now includes an ABSOLUTE PROHIBITION preventing the sync agent from hand-editing anything under src/generated/java/.

The Big Risks

1. sendExpandedToolResult() bypasses the typed wrapper (HIGH)

File: CopilotSession.java, line ~871

The generated SessionToolsHandlePendingToolCallParams.result field is typed as String (the code generator picks String for anyOf[string, object]), but the protocol requires a JSON object (ToolResultObject) for success results. The workaround is sendExpandedToolResult(), which hand-builds an ObjectNode and calls rpc.invoke(...) directly.

What to verify: This is the single place where the typed wrapper is intentionally bypassed. If the protocol ever changes the shape of the result field, this hand-built node will silently produce invalid payloads. Confirm the ObjectNode construction (sessionId, requestId, result as serialized tree) matches what the server expects. Also consider whether the generator's anyOf resolution rule should be improved in a follow-up.

2. Lazy SessionRpc initialization is not thread-safe (HIGH)

File: CopilotSession.java, lines ~300–310

sessionRpc is declared volatile, but the lazy init in getRpc() does a check-then-assign without synchronization:

SessionRpc current = sessionRpc;
if (current == null) {
    sessionRpc = current = new SessionRpc(rpc::invoke, sessionId);
}
return current;

Two threads calling getRpc() simultaneously could both see null and each create a separate SessionRpc instance. Because SessionRpc is stateless (captures only caller + sessionId), duplicating it is harmless — but confirm no state is accumulated on the instance.

Additionally, setActiveSessionId() sets sessionRpc = null to force re-creation on the next getRpc() call. This is safe only because SessionRpc doesn't cache anything mutable.

3. ~200 generated files committed as-is — spot-check against schema (MEDIUM)

The src/generated/java/ tree contains ~70 event classes and ~130 RPC param/result/API classes. They are produced by scripts/codegen/java.ts and committed verbatim. The CI codegen-check.yml workflow verifies they stay in sync with the generator, but does not verify the generator is correct relative to the schema.

What to verify: Spot-check 2–3 generated API classes (e.g., SessionToolsApi.java, SessionUiApi.java) against the corresponding methods in api.schema.json. Confirm the parameter record fields match the JSON schema properties (names, types, required vs optional). The generator output is 100% deterministic, so checking a few representative classes is sufficient.

Fixed in https://github.com/github/copilot-sdk-java/tree/copilot/add-classical-code-gen-workflow-ready-add-copilot-review-to-codegen-step

4. Enum fromValue() is case-sensitive (MEDIUM)

File: SessionUiElicitationResult.java (and all generated enums)

Every generated enum has a @JsonCreator fromValue(String) method that does an exact v.value.equals(value) comparison. If the server ever sends "Accept" or "ACCEPT" instead of "accept", deserialization will throw IllegalArgumentException.

PENDING(edburns): See https://github.slack.com/archives/C09TX0PUJ3Z/p1776456451925629

What to verify: Confirm the Copilot CLI consistently sends lowercase enum values. The comparison in CopilotSession uses == on enum constants (e.g., resp.action() == SessionUiElicitationResultAction.ACCEPT), which is correct — the risk is entirely in the deserialization path.

Gotchas

ServerRpc is eager; SessionRpc is lazy — by design

ServerRpc is created once, eagerly, in the Connection record when CopilotClient.start() connects. SessionRpc is created lazily on first CopilotSession.getRpc() call because the sessionId isn't known until createSession() returns. This asymmetry is intentional, not accidental.

Generated RPC wrappers inject sessionId via ObjectNode mutation

Every method in SessionRpc and its sub-API classes serializes the param record to an ObjectNode, then calls _p.put("sessionId", this.sessionId) to inject the session ID. This means the sessionId field in param records (e.g., SessionToolsHandlePendingToolCallParams.sessionId) is effectively overwritten. Call sites still pass sessionId in the constructor for readability, but the generated wrapper stomps it.

Tests now fail instead of skip when CLI is absent

The old pattern was if (cliPath == null) { return; } which silently skipped. The new TestUtil uses assertNotNull(cliPath, ...) which fails. This is intentional — CI must have the CLI installed.

The events → generated package move changes all import paths

Every test and production file that referenced com.github.copilot.sdk.events.SomethingEvent now imports com.github.copilot.sdk.generated.SomethingEvent. The SessionEvent sealed class (which was AbstractSessionEvent in the old package) is now SessionEvent — a class rename, not just a move.